---
title: LiveStore CLI
description: Command-line interface for LiveStore project scaffolding and development tools.
---

import CliConfigSnippet from '../../../_assets/code/reference/cli/config.ts?snippet'

The LiveStore CLI provides tools for creating new projects and integrating with AI assistants through MCP (Model Context Protocol).

:::caution[Experimental - Not Production Ready]
The LiveStore CLI is an experimental preview and not ready for production use. APIs, commands, and functionality may change significantly. Use for development and evaluation purposes only.
:::

## Installation

You can use the LiveStore CLI in several ways:

```bash
# Recommended: Use bunx (no installation needed)
bunx @livestore/cli --help

# Alternative options:
npm install -g @livestore/cli        # Global install
npm install -D @livestore/cli        # Project install
npx @livestore/cli --help            # Use with npx
```

## Commands

### `livestore new-project`
Create a new LiveStore project from available examples.

```bash
# Interactive selection
livestore new-project

# Specify example and path
livestore new-project --example web-todomvc my-project

# Use specific branch
livestore new-project --branch dev
```

### `livestore mcp`
MCP server tools for AI assistant integration. See [MCP Integration](/building-with-livestore/tools/mcp) for details.

```bash
# Start MCP server
livestore mcp

# Available subcommands
livestore mcp coach    # AI coaching assistant (requires API key env var)
livestore mcp tools    # Development tools server

# Coach command requires API key - check implementation for specific variable name
# Example: OPENAI_API_KEY=your_key livestore mcp coach
```

### `livestore sync`

Import and export events from the sync backend. Useful for backup, migration, and debugging.

#### Export

Export all events from the sync backend to a JSON file:

```bash
livestore sync export \
  --config livestore-cli.config.ts \
  --store-id my-store \
  events.json
```

**Example output:**

```
Exporting events from LiveStore...
   Config: livestore-cli.config.ts
   Store ID: my-store
   Output: events.json

Connecting to sync backend...
✓ Connected to sync backend: @livestore/cf-sync
Pulling events from sync backend...
Pulled 127 events
Exported 127 events to /path/to/events.json
```

**Options:**
- `--config, -c` (required) - Path to a config module that exports `schema` and `syncBackend`
- `--store-id, -i` (required) - Store identifier
- `--client-id` - Client identifier for the sync connection (default: `cli-export`)
- Large exports load data in memory; for very large stores run this on a machine with sufficient RAM.

#### Import

Import events from a JSON file to the sync backend:

```bash
livestore sync import \
  --config livestore-cli.config.ts \
  --store-id my-store \
  events.json
```

**Example output:**

```
Importing events to LiveStore...
   Config: livestore-cli.config.ts
   Store ID: my-store
   Input: events.json

Reading import file...
Found 127 events in export file
Checking for existing events...
Connecting to sync backend...
✓ Connected to sync backend: @livestore/cf-sync
Pushing events to sync backend...
  Pushed 100/127 events
  Pushed 127/127 events
Successfully imported 127 events
```

**Options:**
- `--config, -c` (required) - Path to a config module that exports `schema` and `syncBackend`
- `--store-id, -i` (required) - Store identifier
- `--client-id` - Client identifier for the sync connection (default: `cli-import`)
- `--force, -f` - Force import even if store ID in the file doesn't match
- `--dry-run` - Validate the import file without actually importing
- Large imports are memory-intensive because the JSON is loaded fully before validation/push.

**Note:** The sync backend must be empty when importing. The import will fail if events already exist.

### Config file

Both MCP and sync commands require a config file (conventionally named `livestore-cli.config.ts`) that exports:

<CliConfigSnippet />

## Global options

- `--verbose` - Enable verbose logging
- `--help` - Show command help
